<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="ja">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>uupaa-msgpump.js - Reference</title>
<style type="text/css">@import url(./README.css);</style>
</head>
<body>
<p>
   | <a href="http://code.google.com/p/uupaa-js-spinoff/">Project Home(Google Code)</a>
   | <a href="./README.htm">README</a>
   | <a href="./DEMO.htm">DEMO</a>
   | <a href="./CLASS.htm">Reference</a> |<br />
   | <a href="./CHANGELOG.htm">ChangeLog</a>
   | <a href="./LICENSE.htm">License</a>
   | <a href="./GLOSSARY.htm">Glossary</a>
   |
</p>

<hr />
|
<a href="#uuClass.MsgPump">uuClass.MsgPump</a> |
<a href="#uu.msg">uu.msg</a> |

<hr />
<h2><a name="uuClass.MsgPump">MsgPump</a> - メッセージポンプ</h2>
<p>uuClass.MsgPump は インスタンス間の相互通信機能を提供します。</p>
<p>メッセージポンプを使うと、システムから一斉に配信されるメッセージを受け取ったり、
  特定/不特定のインスタンスとのメッセージの送受信が可能になります。</p>
<p>通信相手の限定もできます。</p>
<ol>
  <li><a href="./GLOSSARY.htm#Unicast">Unicast</a> - 誰か一人にメッセージを送信する(限定)</li>
  <li><a href="./GLOSSARY.htm#Multicast">Multicast</a> - 何人かに同じメッセージを送信する(限定)</li>
  <li><a href="./GLOSSARY.htm#Broadcast">Broadcast</a> - 全ての人に同じメッセージを送信する(公開)</li>
</ol>
<p>uuClass.Generic または uuClass.Singleton で、msgbox メソッドを持つクラスをインスタンス化すると、
   そのインスタンスでは最初からメッセージポンプが使えます。</p>
<pre class="eg">
<u>// uuClass.Generic, uuClass.Singleton なら、メッセージを送受信可能なインスタンスが生成される</u>
var ReceiverClass = <b>uuClass.Generic</b>();
ReceiverClass.prototype = {
  <b>msgbox</b>: function(msg, p1, p2) {
    alert(msg);
  }
};
var recv = new ReceiverClass();
<u>// uu.msg.regist(recv); // regist不要</u>
<b>uu.msg.post</b>(recv, "Hello"); <u>// alert("Hello")</u>
</pre>

<p>uuClass.Generic, uuClass.Singleton 以外の方法で作成したインスタンスがメッセージを受け取るには、以下の条件をクリアする必要があります。</p>
<ul>
  <li>msgbox メソッドをもつ</li>
  <li>uuid プロパティに他のインスタンスと競合しないユニークな値(数値または文字列)をもつ</li>
  <li><a href="#uuClass.MsgPump.regist">uuClass.MsgPump.regist</a> でインスタンスを登録している</li>
</ul>
<p>以下がその例です。</p>

<p><a href="./demo/regist_obj.htm" class="run">Run</a> <a href="#uuClass.MsgPump.post">uuClass.MsgPump.post</a> でメッセージを送信すると、receiverObject.msgbox が呼ばれ "Hello" が表示されます。</p>
<pre class="eg">
function boot() {
  <u>// uuClass.Generic, uuClass.Singleton 以外の方法でメッセージを受け取れるオブジェクトを生成する</u>
  receiverObject1 = {
    <b>uuid</b>: 1,
    <b>msgbox</b>: function(msg, p1, p2) {
      var e = document.getElementById("log");
      e.innerHTML += "&lt;br /&gt;" + msg + " receiverObject1";
    }
  };
  receiverObject2 = {
    <b>uuid</b>: 2,
    <b>msgbox</b>: function(msg, p1, p2) {
      var e = document.getElementById("log");
      e.innerHTML += "&lt;br /&gt;" + msg + " receiverObject1";
    }
  };
  <b>uu.msg.regist</b>(receiverObject1, receiverObject2).<b>post</b>(0, "Hello").<b>post</b>(1, "Hello 1");
}
window.onload = boot;
</pre>
<hr />
<dl>
<!-- -->
  <dt><a name="uu.msg">uu.msg</a> - system instance - システムインスタンス</dt>
  <dd><p>uu.msg は、最初から用意されている uuClass.MsgPump のインスタンスです。</p>
      <p>uu.msg でブロードキャスト送信を行うと、システム全体にメッセージを配信します。</p>

<p><a href="./demo/mygroup.htm" class="run">Run</a> 
    システム全体ではなく、特定のインスタンスが属するグループ内でブロードキャスト通信を行いたい場合は
    uuClass.MsgPump をインスタンス化し、
    新しく作成したメッセージポンプを使って通信を行ってください。</p>
<pre class="eg">
function _msgbox(msg, p1, p2) {
  var e = document.getElementById("log");
  e.innerHTML += "&lt;br /&gt;" + msg;
};
function boot() {
  var obj1 = { uuid: 100, msgbox: _msgbox },
      obj2 = { uuid: 101, msgbox: _msgbox },
      obj3 = { uuid: 102, msgbox: _msgbox };
  var msg = new <b>uuClass.MsgPump</b>();
  msg.<b>regist</b>(obj1, obj2, obj3).<b>post</b>(0, "Hello my group");
}
window.onload = boot;
</pre>
  </dd>

<!-- -->
  <dt><a name="uuClass.MsgPump.regist">uuClass.MsgPump.regist</a> - register the destination of the message - メッセージの送信先を登録</dt>
  <dd><p>uuClass.MsgPump.regist(<i>obj</i>, ...) は、
      uuid プロパティを持つインスタンス(<i>obj</i>)をメッセージの送信先として登録します。</p>
<pre>
@param Object obj - uuid プロパティに uniqueID が設定されているインスタンスを指定します。
                    複数のインスタンスを指定できます。
@return this      - this を返します。
@throws TypeError ""  引数が無効
</pre>
  </dd>
<!-- -->
  <dt><a name="uuClass.MsgPump.unregist">uuClass.MsgPump.unregist</a></dt>
  <dd><p>uuClass.MsgPump.unregist(<i>obj</i>, ...) は、
      uuid プロパティを持つインスタンス(<i>obj</i>)をメッセージの送信先から削除します。</p>
<pre>
@param Object obj - uuid プロパティに uniqueID が設定されているインスタンスを指定します。
                    複数のインスタンスを指定できます。
@return this      - this を返します。
@throws TypeError ""  引数が無効
</pre>
  </dd>

<!-- -->
  <dt><a name="uuClass.MsgPump.send">uuClass.MsgPump.send</a> - send a message synchronously - メッセージを同期送信</dt>
  <dd><p>uuClass.MsgPump.send(<i>to</i>, <i>msg</i>, <i>p1</i> = undefined, <i>p2</i> = undefined) は、
      メッセージを送信し送信結果を返します。<i>p1</i>, <i>p2</i> にはどのような引数でも渡せます。</p>
      <p>メッセージの受け取り側には、msgbox(<i>msg</i>, <i>p1</i>, <i>p2</i>) の形で引数が渡されます。</p>
<pre>
@param Object  to   - メッセージの送信先を指定します。
       /String        以下の型を指定できます。
       /Array         1. Object( instance has uuid property ) - uuid プロパティを持つインスタンス - unicast
       /Number        2. String( "uuid1" ) - uuid文字列 - unicast
                      3. Array( [instance, instance, ...] ) - uuid プロパティを持つインスタンスの配列 - multicast or unicast
                      4. Array( ["uuid1", "uuid2", ...] ) - uuid 文字列の配列 - multicast or unicast
                      5. Number( 0 ) - 数値のゼロ - broadcast
                      有効な uuid(または uuid を持つインスタンス)を一つ指定するとユニキャストします。
                      有効な uuid(または uuid を持つインスタンス)を複数指定するとマルチキャストします。
                      0を指定するとブロードキャストします。
@param String  msg  - メッセージを指定します。
@param Mix     [p1] - 1つめのパラメタの指定です。デフォルトは undefined です。
@param Mix     [p2] - 2つめのパラメタの指定です。デフォルトは undefined です。
@return Array/Mix   - msgbox 関数の戻り値を格納した Array( [戻り値1, 戻り値2, ...] )を返します。
                      ユニキャストの場合は Array ではなく、msgbox 関数の戻り値そのものを返します。
</pre>
  </dd>

<!-- -->
  <dt><a name="uuClass.MsgPump.post">uuClass.MsgPump.post</a> - send a message asynchronously - メッセージを非同期送信</dt>
  <dd><p>uuClass.MsgPump.post(<i>to</i>, <i>msg</i>, <i>p1</i> = undefined, <i>p2</i> = undefined) は、
      メッセージを非同期に送信します。<i>p1</i>, <i>p2</i>にはどのような引数でも渡せます。</p>
      <p>メッセージの受け取り側には、msgbox(<i>msg</i>, <i>p1</i>, <i>p2</i>) の形で引数が渡されます。</p>
<pre>
@param Object  to   - メッセージの送信先を指定します。
       /String        以下の型を指定できます。
       /Array         1. Object( instance has uuid property ) - uuid プロパティを持つインスタンス - unicast
       /Number        2. String( "uuid1" ) - uuid文字列 - unicast
                      3. Array( [instance, instance, ...] ) - uuid プロパティを持つインスタンスの配列 - multicast or unicast
                      4. Array( ["uuid1", "uuid2", ...] ) - uuid 文字列の配列 - multicast or unicast
                      5. Number( 0 ) - 数値のゼロ - broadcast
                      有効な uuid(または uuid を持つインスタンス)を一つ指定するとユニキャストします。
                      有効な uuid(または uuid を持つインスタンス)を複数指定するとマルチキャストします。
                      0を指定するとブロードキャストします。
@param String  msg  - メッセージを指定します。
@param Mix     [p1] - 1つめのパラメタの指定です。デフォルトは undefined です。
@param Mix     [p2] - 2つめのパラメタの指定です。デフォルトは undefined です。
@return this        - this を返します。
</pre>
  <a href="demo/multicast.htm" class="run">Run</a>
<pre class="eg">
var XFile = function(uuid, name) {
  this.<b>uuid</b>  = uuid;
  this.agent = name;
};
XFile.prototype = {
  <b>msgbox</b>: function(msg, p1, p2) {
    var e = document.getElementById("log");
    e.innerHTML += ["&lt;br /&gt;", this.agent, ": accepted message [", msg, "], from ", p1.from].join("");
  }
};
var agent1 = new XFile(1, "Agent Mulder");
var agent2 = new XFile(2, "Agent Scully");
var agent3 = new XFile(3, "Smoking Man");

<b>uu.msg.regist</b>(agent1, agent2, agent3);

<b>uu.msg.post</b>(agent1, "Hello Mulder", { from: "Scully"      }); <u>// スカリーからモルダーにご挨拶</u>
<b>uu.msg.post</b>(0,      "Hi All",       { from: "Mulder"      }); <u>// モルダーが(自分も含め)みんなにご挨拶</u>
<b>uu.msg.send</b>(agent1, "...",          { from: "Smoking Man" }); <u>// スモーキングマンがモルダーだけにお返事</u>
<b>uu.msg.post</b>([agent2, agent3], "Samantha... orz", { from: "Mulder" }); <u>// モルダーが(自分以外に)いつもの</u>
</pre>
  </dd>
</dl>

</body>
</html>
